<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Custom Parsers</title>
<link rel="stylesheet" href="../../../../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Chapter 1. Boost.Beast">
<link rel="up" href="../using_http.html" title="HTTP">
<link rel="prev" href="custom_body_types.html" title="Custom Body Types">
<link rel="next" href="../more_examples.html" title="HTTP Examples">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="custom_body_types.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_http.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../more_examples.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="beast.using_http.custom_parsers"></a><a class="link" href="custom_parsers.html" title="Custom Parsers">Custom Parsers</a>
</h3></div></div></div>
<p>
        While the parsers included in the library will handle a broad number of use-cases,
        the <a class="link" href="../ref/boost__beast__http__basic_parser.html" title="http::basic_parser"><code class="computeroutput"><span class="identifier">basic_parser</span></code></a> interface can be subclassed
        to implement custom strategies for storing parsed results: the basic parser
        processes input buffers into elements according to the HTTP/1 protocol specification,
        while the derived class decides what to do with those elements. Custom parsers
        will work with all of the HTTP stream read algorithms, as those algorithms
        use only the basic parser interface. Some use cases for implementing custom
        parsers are:
      </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
            Inspect incoming header fields and keep or discard them.
          </li>
<li class="listitem">
            Use a container provided by an external interface.
          </li>
</ul></div>
<p>
        The basic parser uses virtual functions. To declare your user-defined parser,
        derive from <a class="link" href="../ref/boost__beast__http__basic_parser.html" title="http::basic_parser"><code class="computeroutput"><span class="identifier">basic_parser</span></code></a> and implement all the
        required virtual functions. A declaration for the derived class may look
        like this:
      </p>
<pre class="programlisting"><span class="keyword">template</span><span class="special">&lt;</span><span class="keyword">bool</span> <span class="identifier">isRequest</span><span class="special">&gt;</span>
<span class="keyword">class</span> <span class="identifier">custom_parser</span> <span class="special">:</span> <span class="keyword">public</span> <span class="identifier">basic_parser</span><span class="special">&lt;</span><span class="identifier">isRequest</span><span class="special">&gt;</span>
<span class="special">{</span>
<span class="keyword">private</span><span class="special">:</span>
    <span class="comment">/** Called after receiving the request-line.

        This virtual function is invoked after receiving a request-line
        when parsing HTTP requests.
        It can only be called when `isRequest == true`.

        @param method The verb enumeration. If the method string is not
        one of the predefined strings, this value will be @ref verb::unknown.

        @param method_str The unmodified string representing the verb.

        @param target The request-target.

        @param version The HTTP-version. This will be 10 for HTTP/1.0,
        and 11 for HTTP/1.1.

        @param ec An output parameter which the function may set to indicate
        an error. The error will be clear before this function is invoked.
    */</span>
    <span class="keyword">void</span>
    <span class="identifier">on_request_impl</span><span class="special">(</span>
        <span class="identifier">verb</span> <span class="identifier">method</span><span class="special">,</span>                <span class="comment">// The method verb, verb::unknown if no match</span>
        <span class="identifier">string_view</span> <span class="identifier">method_str</span><span class="special">,</span>     <span class="comment">// The method as a string</span>
        <span class="identifier">string_view</span> <span class="identifier">target</span><span class="special">,</span>         <span class="comment">// The request-target</span>
        <span class="keyword">int</span> <span class="identifier">version</span><span class="special">,</span>                <span class="comment">// The HTTP-version</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span>   <span class="comment">// The error returned to the caller, if any</span>

    <span class="comment">/** Called after receiving the status-line.

        This virtual function is invoked after receiving a status-line
        when parsing HTTP responses.
        It can only be called when `isRequest == false`.

        @param code The numeric status code.

        @param reason The reason-phrase. Note that this value is
        now obsolete, and only provided for historical or diagnostic
        purposes.

        @param version The HTTP-version. This will be 10 for HTTP/1.0,
        and 11 for HTTP/1.1.

        @param ec An output parameter which the function may set to indicate
        an error. The error will be clear before this function is invoked.
    */</span>
    <span class="keyword">void</span>
    <span class="identifier">on_response_impl</span><span class="special">(</span>
        <span class="keyword">int</span> <span class="identifier">code</span><span class="special">,</span>                   <span class="comment">// The status-code</span>
        <span class="identifier">string_view</span> <span class="identifier">reason</span><span class="special">,</span>         <span class="comment">// The obsolete reason-phrase</span>
        <span class="keyword">int</span> <span class="identifier">version</span><span class="special">,</span>                <span class="comment">// The HTTP-version</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span>   <span class="comment">// The error returned to the caller, if any</span>

    <span class="comment">/** Called once for each complete field in the HTTP header.

        This virtual function is invoked for each field that is received
        while parsing an HTTP message.

        @param name The known field enum value. If the name of the field
        is not recognized, this value will be @ref field::unknown.

        @param name_string The exact name of the field as received from
        the input, represented as a string.

        @param value A string holding the value of the field.

        @param ec An output parameter which the function may set to indicate
        an error. The error will be clear before this function is invoked.
    */</span>
    <span class="keyword">void</span>
    <span class="identifier">on_field_impl</span><span class="special">(</span>
        <span class="identifier">field</span> <span class="identifier">f</span><span class="special">,</span>                    <span class="comment">// The known-field enumeration constant</span>
        <span class="identifier">string_view</span> <span class="identifier">name</span><span class="special">,</span>           <span class="comment">// The field name string.</span>
        <span class="identifier">string_view</span> <span class="identifier">value</span><span class="special">,</span>          <span class="comment">// The field value</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span>   <span class="comment">// The error returned to the caller, if any</span>

    <span class="comment">/** Called once after the complete HTTP header is received.

        This virtual function is invoked once, after the complete HTTP
        header is received while parsing a message.

        @param ec An output parameter which the function may set to indicate
        an error. The error will be clear before this function is invoked.
    */</span>
    <span class="keyword">void</span>
    <span class="identifier">on_header_impl</span><span class="special">(</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span>   <span class="comment">// The error returned to the caller, if any</span>

    <span class="comment">/** Called once before the body is processed.

        This virtual function is invoked once, before the content body is
        processed (but after the complete header is received).

        @param content_length A value representing the content length in
        bytes if the length is known (this can include a zero length).
        Otherwise, the value will be `boost::none`.

        @param ec An output parameter which the function may set to indicate
        an error. The error will be clear before this function is invoked.
    */</span>
    <span class="keyword">void</span>
    <span class="identifier">on_body_init_impl</span><span class="special">(</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special">&lt;</span>
            <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span><span class="special">&gt;</span> <span class="keyword">const</span><span class="special">&amp;</span>
                <span class="identifier">content_length</span><span class="special">,</span>     <span class="comment">// Content length if known, else `boost::none`</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span>   <span class="comment">// The error returned to the caller, if any</span>

    <span class="comment">/** Called each time additional data is received representing the content body.

        This virtual function is invoked for each piece of the body which is
        received while parsing of a message. This function is only used when
        no chunked transfer encoding is present.

        @param body A string holding the additional body contents. This may
        contain nulls or unprintable characters.

        @param ec An output parameter which the function may set to indicate
        an error. The error will be clear before this function is invoked.

        @see on_chunk_body_impl
    */</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span>
    <span class="identifier">on_body_impl</span><span class="special">(</span>
        <span class="identifier">string_view</span> <span class="identifier">s</span><span class="special">,</span>              <span class="comment">// A portion of the body</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span>   <span class="comment">// The error returned to the caller, if any</span>

    <span class="comment">/** Called each time a new chunk header of a chunk encoded body is received.

        This function is invoked each time a new chunk header is received.
        The function is only used when the chunked transfer encoding is present.

        @param size The size of this chunk, in bytes.

        @param extensions A string containing the entire chunk extensions.
        This may be empty, indicating no extensions are present.

        @param ec An output parameter which the function may set to indicate
        an error. The error will be clear before this function is invoked.
    */</span>
    <span class="keyword">void</span>
    <span class="identifier">on_chunk_header_impl</span><span class="special">(</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span> <span class="identifier">size</span><span class="special">,</span>         <span class="comment">// The size of the upcoming chunk,</span>
                                    <span class="comment">// or zero for the last chunk</span>
        <span class="identifier">string_view</span> <span class="identifier">extension</span><span class="special">,</span>      <span class="comment">// The chunk extensions (may be empty)</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span>   <span class="comment">// The error returned to the caller, if any</span>

    <span class="comment">/** Called each time additional data is received representing part of a body chunk.

        This virtual function is invoked for each piece of the body which is
        received while parsing of a message. This function is only used when
        no chunked transfer encoding is present.

        @param remain The number of bytes remaining in this chunk. This includes
        the contents of passed `body`. If this value is zero, then this represents
        the final chunk.

        @param body A string holding the additional body contents. This may
        contain nulls or unprintable characters.

        @param ec An output parameter which the function may set to indicate
        an error. The error will be clear before this function is invoked.

        @return This function should return the number of bytes actually consumed
        from the `body` value. Any bytes that are not consumed on this call
        will be presented in a subsequent call.

        @see on_body_impl
    */</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">size_t</span>
    <span class="identifier">on_chunk_body_impl</span><span class="special">(</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">uint64_t</span> <span class="identifier">remain</span><span class="special">,</span>       <span class="comment">// The number of bytes remaining in the chunk,</span>
                                    <span class="comment">// including what is being passed here.</span>
                                    <span class="comment">// or zero for the last chunk</span>
        <span class="identifier">string_view</span> <span class="identifier">body</span><span class="special">,</span>           <span class="comment">// The next piece of the chunk body</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span>   <span class="comment">// The error returned to the caller, if any</span>

    <span class="comment">/** Called once when the complete message is received.

        This virtual function is invoked once, after successfully parsing
        a complete HTTP message.

        @param ec An output parameter which the function may set to indicate
        an error. The error will be clear before this function is invoked.
    */</span>
    <span class="keyword">void</span>
    <span class="identifier">on_finish_impl</span><span class="special">(</span>
        <span class="identifier">error_code</span><span class="special">&amp;</span> <span class="identifier">ec</span><span class="special">)</span> <span class="identifier">override</span><span class="special">;</span>   <span class="comment">// The error returned to the caller, if any</span>

<span class="keyword">public</span><span class="special">:</span>
    <span class="identifier">custom_parser</span><span class="special">()</span> <span class="special">=</span> <span class="keyword">default</span><span class="special">;</span>
<span class="special">};</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2016-2019 Vinnie
      Falco<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="custom_body_types.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_http.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="../more_examples.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
